Custom integration field in product GraphQL APIs

^{Major Upgrade}

This release introduces support for managing the custom integration field through our Product GraphQL APIs. This will enable the ability to more easily manage products with custom integrations in bulk and at scale, such as Microsoft and Adobe.Previously, this functionality was only available to Superusers in the Product Management user interface or via a ZIP import workaround. This new capability has built-in protections against invalid custom integration values, which protects API users from breaking product integrations.

Customer impact

• Enhanced API capabilities
  Customers needing to manage their product catalogs via API can now create and manage custom integration settings directly through GraphQL mutations. This removes the need for ZIP import workarounds or superuser UI access.
• Improved developer experience
  
  • Configure or update products with custom integration in a single API call.
  • Query integration status alongside other product fields.
  • Reduce context switching between UI and API interfaces.
• Security maintained
  
  • Adheres to existing permission and validation checks.
  • Only users with tenant-level permissions (ROLE_CHANNEL_ADMIN or ROLE_PARTNER) can modify integration fields.

Key changes

Aspect	Change
API access	New customIntegration field added to createProduct and updateProduct mutations for programmatic configuration.
Query capability	New customIntegration field added to the Product type for querying integration status.
Permission model	Write operations (set or clear custom integration) require ROLE_CHANNEL_ADMIN or ROLE_PARTNER.
Validation	Server-side validation enforces valid integration type strings (consistent with ZIP import validation).
Error handling	Introduced InsufficientCustomIntegrationPermissionError and InvalidCustomIntegrationError for structured error reporting.
Update behavior	Support for explicitly clearing custom integration by setting field to null, with permission checks for clearing operations.
Create behavior	Omitted or null customIntegration field creates products without custom integration (no permission check required).
Schema design	Field exposed as String type (not enum) to maintain privacy of vendor integration types and business relationships.

GraphQL API changes

Mutations:

createProduct

• Input:
  • Added optional customIntegration: String field to CreateProductInput.
• Behavior:
  • Accepts valid integration type strings (example - "GOOGLE_APPS", "DOCUSIGN", "ZOOM", "ADOBE").
  • Requires ROLE_CHANNEL_ADMIN or ROLE_PARTNER for setting a value.
  • Omitting or setting to null creates a product without a custom integration.
• Error Responses:
  • InsufficientCustomIntegrationPermissionError – User lacks required permissions.
  • InvalidCustomIntegrationError – Invalid integration type value.

updateProduct

• Input:
  • Added optional customIntegration: String field to UpdateProductInput.
• Behavior:
  • Accepts valid integration type strings or null to clear custom integration.
  • Setting a value or clearing (setting to null) requires ROLE_CHANNEL_ADMIN or ROLE_PARTNER permission.
  • Omitting the field preserves the existing integration value.
• Error Responses:
  • InsufficientCustomIntegrationPermissionError – User lacks required permissions.
  • InvalidCustomIntegrationError – Invalid integration type value.

Query:

Product type

• New Field: Added customIntegration: String field to Product type.
• Behavior:
  • Returns the integration type (example - "GOOGLE_APPS", "DOCUSIGN") or null if not set.
  • Readable by all authenticated users with product access (ROLE_DEVELOPER, ROLE_CHANNEL_ADMIN, or ROLE_PARTNER).

New error types

Error type	Description	When returned
InsufficientCustomIntegrationPermissionError	Indicates that the user attempted to set or clear a custom integration without proper permissions.	When a user lacks ROLE_CHANNEL_ADMIN or ROLE_PARTNER.
InvalidCustomIntegrationError	Indicates that an invalid string value was provided for the integration type.	When input value does not match internal validation constants.

Validation rules

Validation type	Rule
Permission validation	Only ROLE_CHANNEL_ADMIN or ROLE_PARTNER can set or clear integration values.
Value validation	Accepted values must match valid integration type constants.
Create behavior	Null or omitted values create a product without a custom integration (no permission check).
Update behavior	Omitting preserves existing value; setting to null clears the field (requires permission).

Feature enablement

No feature enablement is required.

Setting enablement

No setting enablement is required.

Documentation

Documentation will be updated with the release.